import { Meta } from '@storybook/addon-docs';

<Meta title="Concepts/Migration/from v8/Component Mapping" />

# Component Migration

- [Getting Started](#getting-started)
- [Component Mapping](#component-mapping)
- [Deprecated Components](#deprecated-components)
- [New Components in v9](#new-components-in-v9)
- [Additional Resources](#additional-resources)

---

# Getting Started

1. **Install Fluent UI v9**:
   To begin migration, install the latest Fluent UI React v9 package.

   ```bash
   npm install @fluentui/react-components
   ```

2. **Update Imports**:
   Update your component imports to use the v9 components. Use the component mapping table below to assist.

3. **Refactor Code**:
   Refactor your code to accommodate changes in API, props, and new functionalities provided by v9 components.

---

# Component Mapping

Here is the mapping of v8 components to their v9 component replacement or equivalent. This table provides a side-by-side comparison of React v8 components and their corresponding counterparts in React v9. Where a direct v9 equivalent doesn't exist, an alternative or note is provided.

- Blank cells mean that there is not a v9 component (yet) or the component did not exist in v8.
- A (🔁) means the v9 component is currently being developed. It may be in preview or not exported from react-components yet.
  Check out the latest schedule information on the [v9 Component Roadmap](https://github.com/microsoft/fluentui/wiki/Fluent-UI-React-v9-Component-Roadmap)

| **React v8 Component**   | **React v9 Component**                                                                                                                           | **Notes**                                                                    |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| `ActionButton`           | [`Button`](/docs/components-button-button--docs)                                                                                                 | Use `Button` with `iconPosition="before"` for similar functionality.         |
| `ActivityItem`           | Not available                                                                                                                                    | No direct equivalent in v9; custom implementation needed.                    |
| `Announced`              | Not available                                                                                                                                    | No direct equivalent in v9.                                                  |
| `Breadcrumb`             | [`Breadcrumb`](/docs/components-breadcrumb--docs)                                                                                                | No major changes; available in v9.                                           |
| `Button`                 | [`Button`](/docs/components-button-button--docs)                                                                                                 | Unified button API; use `appearance` prop for variants like `PrimaryButton`. |
| `Callout`                | [`Popover` ](/docs/components-popover--docs)                                                                                                     | Replaced by `Popover`, with enhanced accessibility and customization.        |
| `Calendar`               | [`CalendarCompat`](/docs/compat-components-calendar--docs)                                                                                       | Use the compact variant in v9.                                               |
| `CommandBar`             | [`Toolbar`](/docs/components-toolbar--docs)                                                                                                      | Similar functionality in v9.                                                 |
| `CommandBarButton`       | [`Toolbar`](/docs/components-toolbar--docs)                                                                                                      | Similar functionality in v9.                                                 |
| `CommandButton`          | [`MenuButton`](/docs/components-button-docs--docs)                                                                                               | Similar functionality in v9.                                                 |
| `CompoundButton`         | [`CompoundButton`](/docs/components-button-compoundbutton--docs)                                                                                 | Similar functionality in v9.                                                 |
| `Charts`                 | [`Migration Guide`](/docs/concepts-migration-from-v8-components-charts-migration--page)                                                          | No direct equivalent in v9.                                                  |
| `Checkbox`               | [`Checkbox`](/docs/components-checkbox--docs)                                                                                                    | API remains mostly the same in v9.                                           |
| `ChoiceGroup`            | [`RadioGroup`](/docs/components-radiogroup--docs)                                                                                                | Renamed to `RadioGroup` with similar functionality.                          |
| `Coachmark`              | [`TeachingPopover`](/docs/components-teachingpopover--docs)                                                                                      | Use `TeachingPopover` in v9 for the same functionality.                      |
| `ColorPicker`            | 🔁                                                                                                                                               | No major changes in v9.                                                      |
| `ComboBox`               | [`Combobox`](/docs/components-combobox--docs)                                                                                                    | Renamed to `Combobox` with API improvements.                                 |
| `CommandBar`             | [`Toolbar`](/docs/components-toolbar--docs)                                                                                                      | CommandBar replaced by `Toolbar` for managing actions.                       |
| `ContextualMenu`         | [`Menu`](/docs/components-menu-menu--docs) with Button as the `MenuTrigger`                                                                      | Use `Menu` in v9 with `MenuTrigger`.                                         |
| `DefaultButton (anchor)` | [`Button`](/docs/components-button-button--docs)                                                                                                 | Use `Button` in v9.                                                          |
| `DefaultButton (menu)`   | [`MenuButton`](/docs/components-button-menubutton--docs)                                                                                         | Use `Button` in v9.                                                          |
| `DatePicker`             | [`DatePickerCompat`](/docs/compat-components-datepicker--docs)                                                                                   | API remains similar with enhanced theming options.                           |
| `DetailsList`            | [`DataGrid`](/docs/components-datagrid--docs)                                                                                                    | Experimental `DataGrid` in v9 could be a substitute.                         |
| `Dialog`                 | [`Dialog`](/docs/components-dialog--docs)                                                                                                        | Refined API, using `open` and `onOpenChange` props.                          |
| `DocumentCard`           | [`Card`](/docs/components-card-card--docs)                                                                                                       | Use `Card` in v9.                                                            |
| `Dropdown`               | [`Dropdown`](/docs/components-dropdown--docs)                                                                                                    | API and performance enhancements.                                            |
| `Fabric`                 | `FluentProvider`                                                                                                                                 | Use `FluentProvider` for managing themes and global context.                 |
| `Facepile`               | [`AvatarGroup`](/docs/components-avatargroup--docs)                                                                                              | Replaced by `AvatarGroup` in v9.                                             |
| `FocusTrapZone`          | [`Tabster`](https://tabster.io/)                                                                                                                 | Use `Tabster`.                                                               |
| `FocusZone`              | [`Tabster`](https://tabster.io/)                                                                                                                 | Use `Tabster`.                                                               |
| `GroupedList`            | [`Tree`](/docs/components-tree--docs)                                                                                                            | Use `Tree` in v9.                                                            |
| `HoverCard`              | Not available                                                                                                                                    | No direct equivalent; could use `Popover` with custom behavior.              |
| `Icon`                   | [`@fluentui/react-icons package`](/docs/icons-overview--docs)                                                                                    | v9 provides more customization options.                                      |
| `IconButton`             | [`Button`](/docs/components-button-button--docs)                                                                                                 | v9 provides more customization options.                                      |
| `Image`                  | [`Image`](/docs/components-image--docs)                                                                                                          | No major changes in v9.                                                      |
| `Keytips`                | 🔁                                                                                                                                               | No major changes in v9.                                                      |
| `Label`                  | [`Label`](/docs/components-label--docs)                                                                                                          | Similar functionality in v9.                                                 |
| `Layer`                  | [`Portal`](/docs/components-portal--docs)                                                                                                        | Use `Portal` for similar layering behavior.                                  |
| `Link`                   | [`Link`](/docs/components-link--docs)                                                                                                            | Available in v9, with better accessibility handling.                         |
| `List`                   | 🔁                                                                                                                                               | Enhanced performance in v9.                                                  |
| `MarqueeSelection`       | Not available                                                                                                                                    | No direct equivalent in v9.                                                  |
| `MessageBar`             | [`MessageBar`](/docs/components-messagebar--docs)                                                                                                | Available in v9, with better accessibility handling.                         |
| `Modal`                  | [`Dialog`](/docs/components-dialog--docs)                                                                                                        | Dialog in v9 serves the modal role with updated API.                         |
| `Nav`                    | 🔁                                                                                                                                               | No major changes; available in v9 with improvements.                         |
| `OverflowSet`            | [`Dialog`](/docs/components-overflow--docs)                                                                                                      | No direct equivalent; consider `Dialog` for overflow menus.                  |
| `Overlay`                | [`Portal`](/docs/components-portal--docs)                                                                                                        | Replaced with `Dialog` in v9.                                                |
| `Panel`                  | [`Drawer`](/docs/components-drawer--docs)                                                                                                        | Replaced by `Drawer` for side panel navigation.                              |
| `Popup`                  | [`Dialog`](/docs/components-dialog--default)                                                                                                     | Replaced by `Dialog`                                                         |
| `PeoplePicker`           | [`TagPicker`](/docs/components-tagpicker--docs)                                                                                                  | Replaced by `TagPicker` for improved functionality.                          |
| `Persona`                | [`Persona`](/docs/components-persona--docs)                                                                                                      | No major changes; available in v9 with improvements.                         |
| `Pickers`                | Not available                                                                                                                                    | No direct equivalent in v9.                                                  |
| `Pivot`, `PivotItem`     | [`TabList`, `Tab`](/docs/components-tablist--docs)                                                                                               | Replaced by `TabList` in v9.                                                 |
| `ProgressIndicator`      | [`ProgressBar`](/docs/components-progressbar--docs)                                                                                              | Renamed to `ProgressBar` in v9; similar functionality.                       |
| `Rating`                 | [`Rating`](/docs/components-rating--docs)                                                                                                        | Available in v9 with slight API refinements.                                 |
| `ResizeGroup`            | Not available                                                                                                                                    | No direct equivalent in v9.                                                  |
| `ScrollablePane`         | Not available                                                                                                                                    | No direct equivalent in v9.                                                  |
| `SearchBox`              | [`SearchBox`](/docs/components-searchbox--docs)                                                                                                  | Available in v9 with updated API and better accessibility.                   |
| `Separator`              | [`Divider`](/docs/components-divider--docs)                                                                                                      | Replaced by `Divider` in v9.                                                 |
| `Shimmer`                | [`Skeleton`](/docs/components-skeleton--docs)                                                                                                    | Updated to `Skeleton` in v9 for loading states.                              |
| `Slider`                 | [`Slider`](/docs/components-slider--docs)                                                                                                        | API enhancements for better customization.                                   |
| `SplitButton`            | [`Menu with SplitButton as the Menu Trigger`](/docs/components-button-splitbutton--docs)                                                         | Various updates done in v9.                                                  |
| `SpinButton`             | [`SpinButton`](/docs/components-spinbutton--docs)                                                                                                | Available in v9 with improved API.                                           |
| `Spinner`                | [`Spinner`](/docs/components-spinner--docs)                                                                                                      | Available in v9 with better control over animations.                         |
| `Stack`                  | [`Migration Guide`](/docs/concepts-migration-from-v8-components-flex-stack--page), [`StackShim`](/docs/migration-shims-v8-stackshim--playground) | Various changes in v9.                                                       |
| `SwatchColorPicker`      | [`SwatchPicker`](/docs/components-swatchpicker--docs)                                                                                            | Replaced by `SwatchPicker` in v9 for color selection.                        |
| `TagPicker`              | [`TagPicker`](/docs/components-tagpicker--docs)                                                                                                  | No major changes; retained as `TagPicker`.                                   |
| `TeachingBubble`         | [`TeachingPopover`](/docs/components-teachingpopover--docs)                                                                                      | Replaced by `TeachingPopover` in v9.                                         |
| `Text`                   | [`Text`](/docs/components-text--docs)                                                                                                            | Similar functionality in v9.                                                 |
| `TextField`              | [`Input`](/docs/components-input--docs)                                                                                                          | Replaced by `Input` in v9 for text input functionality.                      |
| `ThemeProvider`          | [`FluentProvider`](/docs/components-fluentprovider--docs)                                                                                        | Replaced by `FluentProvider` in v9; similar behavior.                        |
| `TimePicker`             | [`TimePickerCompat`](/docs/compat-components-timepicker--docs)                                                                                   | Replaced by `TimePickerCompat` in v9; similar behavior.                      |
| `ToggleButton`           | [`ToggleButton`](/docs/components-button-togglebutton--docs)                                                                                     | No major changes in v9.                                                      |
| `Toggle`                 | [`Switch`](/docs/components-switch--docs)                                                                                                        | Renamed to `Switch` in v9; similar behavior.                                 |
| `Tooltip`                | [`Tooltip`](/docs/components-tooltip--docs)                                                                                                      | No major changes in v9.                                                      |

## New Components in v9

React v9 introduces several new components that were not present in v8:

- [**Accordion**](/docs/components-accordion--docs): Allowing to toggle the display of content by expanding or collapsing sections.
- [**Avatar**](/docs/components-avatar--docs): Replaces `Persona` for rendering user images.
- [**AvatarGroup**](/docs/components-avatargroup--docs): Replaces `Facepile`.
- [**Badge**](/docs/components-badge-badge--docs): Displays text and/or an icon.
- [**CounterBadge**](/docs/components-badge-counter-badge--docs): Displays Badge numerical values.
- [**PresenceBadge**](/docs/components-badge-presencebadge--docs): Displays Badge status.
- [**Carousel**](/docs/components-carousel--docs): Sliding window of elements controlled by previous, next, and direct pagination buttons.
- [**Drawer**](/docs/components-drawer--docs): Replaces `Panel` for side-drawer navigation.
- [**InfoLabel**](/docs/components-badge-presencebadge--docs):An InfoLabel is a Label with an InfoButton at the end.
- [**Popover**](/docs/components-popover--docs): Enhanced version of `Callout` with improved accessibility.
- [**TabList**](/docs/components-tablist--docs): Replaces `Pivot` for tabbed navigation.
- [**ProgressBar**](/docs/components-progressbar--docs): Renamed from `ProgressIndicator`, with similar functionality but refined API.
- [**Input**](/docs/components-input--docs): A new input component replacing `TextField` for simpler text input handling.
- [**Skeleton**](/docs/components-skeleton--docs): A new input component replacing `Shimmer`.
- [**Switch**](/docs/components-switch--docs): A new component replacing `Toggle` for binary options.
- [**SwatchPicker**](/docs/components-swatchpicker--docs): A new component replacing `SwatchColorPicker` with added functionality.
- [**Toast**](/docs/components-badge-presencebadge--docs):A Toasts displays temporary content to the user.
- [**TeachingPopover**](/docs/components-teachingpopover--docs): A new component in v9 that replaces `TeachingBubble` and `Coachmark` in v8.

## Deprecated Components

Some components in React v8 are not present in v9 or been replaced. Here’s a list of deprecated components:

- **`Coachmark`**
- **`ActivityItem`**
- **`Hovercard`**
- **`MarqueeSelection`**
- **`ResizeGroup`**
- **`ScrollablePane`**
- **`DetailsList`**
- **`Pickers`**
- **`Popup`**

## Additional Resources

For more information on Fluent UI v9, consult these resources:

- [Fluent UI Extensions Packages](https://github.com/microsoft/fluentui-contrib)
- [Fluent 2 Design System Website](https://fluent2.microsoft.design/)
- [Fluent UI GitHub](https://github.com/microsoft/fluentui)

---
